home *** CD-ROM | disk | FTP | other *** search
/ Otherware / Otherware_1_SB_Development.iso / mac / util / editor / alpha513.cpt / Help / Alpha Tcl Extensions < prev    next >
Text File  |  1992-10-24  |  15KB  |  284 lines
  1. ==============================================================================
  2. = Alpha's Additional Tcl Commands
  3. ==============================================================================
  4.  
  5. In this list of routines, text between '<' and '>' is a placeholder for a 
  6. required parameter. Text between '[' and ']' is a placeholder for an 
  7. optional parameter, and the '|' signifies a choice of two alternatives.
  8.  
  9. The following are Alpha-specific tcl routines:
  10.  
  11. Ñ alertnote message_string
  12.   This command will display message_string in a standard Macintosh alert box.
  13. Ñ ascii (see bindings).
  14. Ñ askyesno prompt
  15.   This command will display a Macintosh alert box with promptdisplayed with the 
  16.   push buttons Yes, No, Cancel.. The command will return the title of the button 
  17.   selected by the user.
  18. Ñ beep
  19. Ñ bind  (see bindings)
  20. Ñ blink <pos> - blink cursor at 'pos'
  21. Ñ breakIntoLines <string> - return 'string' with 
  22.   carriage returns and spaces inserted to satisfy 
  23.   'leftFillColumn' and 'fillColumn' variables.
  24. Ñ bringToFront <winName> - Bring named window to front.
  25. Ñ cd [directory]
  26.   This command will set the current working directory to "directory". The directory 
  27.   argument may or may not end with a colon. The working directory is the directory 
  28.   in which file names that contain no colons (folders) will be located with file related 
  29.   commands. No argument means Alpha's home directory.
  30. Ñ colors <fore red> <fore green> <fore blue> <back red> <back green> <back blue>
  31. Ñ cp <fromName> <toName> [force]
  32.   This command will copy the file fromName and name the new file toName. If 
  33.   toName includes a path name that is different from the path in fromName, the copy 
  34.   will be made in a new directory (specified by toName). The copy can be made 
  35.   across volume (disk drives). The force option indicates that the copy should 
  36.   overwrite any existing file with the same name as toName. This command copies 
  37.   both data forks, and the Finder information.
  38. Ñ createTMark <name> <pos> - create a temporary 'mark' 
  39.   at location 'pos'. 
  40. Ñ ctime <time>
  41.   This command will return a UNIX time string of the format "Wed Feb 19 
  42.   22:43:36 1992". The parameter time is in Macintosh seconds, and would be the 
  43.   result of a now or file mtime command or the like.
  44. Ñ deleteText <pos1> <pos2> - remove text between 'pos1' 
  45.   and 'pos2'
  46. Ñ displayMode <mode> - Up to four characters of the 'mode' string are 
  47.   displayed in the status line at the bottom of a window.
  48. Ñ dosc <-c 'sign' | -n appName> <-s string | -f fileName> [-t timeout]
  49.   Send a 'misc' 'dosc' AppleEvent. Options are the following:
  50.    -c 'sign' 
  51.            "sign" is a four-letter creator signature of a running application.
  52.    -n appName
  53.            "appName" is the name of a running application.
  54.    -s string
  55.            "string" is the text of a script to send to the other app.
  56.    -f fileName
  57.            "fileName" is the complete or relative pathname of a file the other 
  58.            application should execute.
  59.    -t timeout
  60.            "timeout" is the number of ticks Alpha should wait for a response. A 
  61.            timeout of "0" means wait forever.
  62.    If neither of the '-c' and '-n' options is chosen, the PPC Browser is 
  63.    used. Either '-s' or '-f' must be chosen. Thus, you can have "Alpha 
  64.    5.02" and "Alpha 5.02 Copy" sending Apple events to each other, or they 
  65.    can send events to a remote server such as Apple's ToolServer. 
  66.  
  67. Ñ echo <string> [<string>...] - echo the strings (used 
  68.   in shells).
  69. Ñ edit <name> [-r] [-m] - Open a file in a new window. '-r' means open 
  70.   the file read-only. '-m' means omit the function titlebar menu and  
  71.   present only the marks titlebar menu, which is labeled with the 
  72.   contents of 'markLabel'.
  73. Ñ fileMenu [-n name] [-d dir] [-r] [-m] <list of menu items> - Defines a new user 
  74.   menu named 'name'. The menu is not yet inserted into the menubar. The menu 
  75.   commands may be nested for heirarchical menus, see 'AlphaBits.tcl' for 
  76.   examples. Unlike the 'menu' command, when items of this type of menu 
  77.   are selected the text is interpreted as a file-name, and Alpha attempts 
  78.   to open that file. '-d' allows defining of a 'dir' argument that is 
  79.   prepended to every file name before the file is opened. '-n' allows 
  80.   naming of the menu, '-r' means open the file readonly, while 
  81.   '-m' means show only the mark menu and use 'markLabel' as it's title.
  82. Ñ get_directory
  83.   This command will display a standard Macintosh file dialog and request the user 
  84.   select a folder. The command will return the selected folder's full path name, or an 
  85.   empty string if the Cancel button was selected.
  86. Ñ getenv <varname>
  87.   This command will return the value of the environment variable varname. 
  88.   Environment variables are initialized by reading the file Ñtclenv. The environment 
  89.   file has the format varname=value as in the following example:
  90.  
  91.     TERM=vt100
  92.     TCLINIT=::tcl:TclInit.tcl
  93.     TCLDEFAULT=
  94.     TEST=TEST
  95.     TCLPATH=::tcl:tclsh:tclsrc
  96.  
  97. Ñ getfile <prompt>
  98.   This command will display an SFGetFile() and return the full path name of the 
  99.   selected file, or an empty string if CANCEL button was selected.
  100. Ñ getfinfo <fileName>
  101.   This command will display the standard Macintosh file information in the form:
  102.   "'aeQL' 'QUIL' lvbsIdm 02/17/92 23:57:12 02/19/92 22:43:36 0,156 219 0".
  103.   The fields are the fdCreator, fdType, fdFlags, flCreationDate, flCreationtime, 
  104.   flModDate, flModTime, fdLocation.H,V, dataForlLength, rsrcForkLength, 
  105.   respectively. The fdFlags field uses characters to represent bits:
  106.     l/L    not locaked/Locked
  107.     v/V    visible/notVisible
  108.     b/B    not bundled/Bundled
  109.     s/S    not system/System
  110.     i/I    not initialized/Initialized
  111.     d/D    not desktop/Desktop
  112.     m/M    not sharable/sharable
  113. Ñ getGeometry - return a TCL list containing the left 
  114.   edge of the current window, the top, the width, and
  115.   height.
  116. Ñ getline <prompt> <default>
  117.   This command will display a Macintosh alert box with promptdisplayed, a text edit 
  118.   field with default initially in the field, and with the push buttons OK, Cancel.. The 
  119.   command will return the text entered into the text edit field by the user, or an empty 
  120.   string if the user selected the Cancel button.
  121. Ñ getMark - return the current mark.
  122. Ñ getPathName - prompt the user with an SFGetFile dialog and return 
  123.   complete pathname.
  124. Ñ getPos - return the current insertion point
  125. Ñ getSelect - return the currently selected text, if 
  126.   any.
  127. Ñ getText <pos1> <pos2> - return the text between 'pos1' 
  128.   and 'pos2'.
  129. Ñ getVar <name> - return the value of the Alpha variable
  130.   'name'.
  131. Ñ glob [-i] [-t <TYPE>] [-c <CRTR>]
  132.   The original glob provided by the UNIX version of tcl was not quite 
  133.   adequate for the more complex Macintosh file system. Issues such as 
  134.   invisible file handling, Finder type and creator filtering, and space 
  135.   handling in file names. Release 6 of tcl has dealt with the original 
  136.   problem with spaces in filenames, but the following options are provided 
  137.   to deal with additional Macintosh issues. 
  138.  
  139. Anyhow, the new glob now takes several options. They are:
  140.     -i    This option causes glob to list invisible files also.
  141.     -t TYPE    This option causes glob to only list file with the 
  142.         indicated Finder file typeTYPE. This option may be 
  143.         used with the -c option.
  144.     -c CRTR    This option causes glob to only list file with the 
  145.         indicated Finder file creatorCRTR. This option may 
  146.         be used with the -t option.
  147.         Also note that the original glob would skip dot files
  148.         (i.e., file names the begin with a period) 
  149.         in the listing, unless the pattern began with a period.
  150.         Tickle extends this concept one step further on the
  151.         Macintosh, and skips spot files (i.e., file names that 
  152.         begin with 'Ñ'), unless the pattern starts with a spot.
  153. Ñ goto <pos> - goto the position 'pos'.
  154. Ñ gotoTMark <name> - goto the temporary mark 'name'.
  155. Ñ hiliteMenuItem <menuName> <itemNum> <on|off> - Either
  156.   enable or disable the 'itemNum'th menu item of user
  157.   menu 'menuName. Note that unless the menu is not only created, but also 
  158.   inserted, this command has no effect.
  159. Ñ insertMenu <name> - insert the previously created user
  160.   menu 'name' into the menuBar.
  161. Ñ insertText [-w <win name>] <text> [<text>]... - Insert 'text' at the current 
  162.   insertion point.
  163. Ñ launch -f <name> - launch the named app into the background. Note that 
  164.   for some yet unexplained reason, some applications (MicroSoft Word) 
  165.   won't launch completely in the background. 'launch'ing such 
  166.   applications won't insert the application into any system menu that 
  167.   specifies running applications (although "About the Finder..." will 
  168.   list it. The only way to get to such an app is through Alpha's 
  169.   'switchTo', after which the application will finish launching. The '-f' 
  170.   option gets around this by launching the application in the foreground 
  171.   instead.
  172. Ñ lineStart <pos> - return the position of the start of
  173.   the line 'pos' is on.
  174. Ñ listpick [-p <prompt>] <list>
  175.   This command will display a dialog with the list displayed in a List Manager list. If 
  176.   the user presses the Cancel button, an empty string is returned. If the user selects 
  177.   the Open button, or double clicks an item in the list, that item will be returned.
  178. Ñ lookAt <pos> - return the 'pos'th character of the 
  179.   current file.
  180. Ñ maxPos - returns the number of characters in the front
  181.   window.
  182. Ñ menu [-n name] <list of menu items> - Defines a new user
  183.   menu named 'name' (if provided). The menu is not yet inserted into 
  184.   the menubar. The menu commands may be nested for 
  185.   heirarchical menus, see 'AlphaBits.tcl' for examples.
  186.   Alpha massages the function names to make them look better
  187.   in the menus.
  188. Ñ message <string> - prints 'string' on the status line.
  189. Ñ mkdir <name> - creates a directory (folder) named 
  190.   'name' in the current directory.
  191. Ñ moveWin [win name] <left> <top> - moves current or specified window.
  192. Ñ mtime <time> [long|short|abbrev]
  193.   Returns a date and time string using the Macintosh International Utilities. The 
  194.   long/short/abbrev specification corresponds to the date. These are the following 
  195.   formats:
  196.     short        3/16/92 9:20:46 PM
  197.     abbrev    Mon, Mar 16, 1992 9:20:49 PM
  198.     long        Monday, March 16, 1992 9:20:43 PM
  199. Ñ mv <fromName> <toName> [force]
  200.   This command will move the file fromName to toName. If toName includes a path 
  201.   name that is different from the path in fromName, the file will be moved into a new 
  202.   directory (specified by toName). The move can not be made across volume (disk 
  203.   drives). The force option indicates that the move should overwrite any existing file 
  204.   with the same name as toName.
  205. Ñ nextLineStart <pos> - return the position of the start 
  206.   of the next line after position 'pos'.
  207. Ñ now
  208.   Returns the current time as Macintosh seconds. This is the number of seconds that 
  209.   have elapsed since Midnight Jan 1, 1904. Appropriate for input to ctime.
  210. Ñ posToRowCol <pos> - converts from absolute position to row, col.
  211. Ñ prompt <prompt> <default> [<name> <menu item>...]
  212.   - prompt dialog to the user with a prompt string and a
  213.   default value. The prompt dialog can optionally 
  214.   include a popup menu specified by 'name' and the 
  215.   succeeding strings. Selection of the popup menu items 
  216.   inserts the item text into the editable dialog item. 
  217.   'Prompt' returns the value of the editable item.
  218. Ñ putenv <varname> <value>
  219.   This command will set the environment variable varname to value.
  220. Ñ putfile <prompt> <original>
  221.   This command will display an SFPutFile() and return the full path name of the 
  222.   selected file, or an empty string if CANCEL button was selected. Original is the 
  223.   default name displayed for the user.
  224. Ñ pwd
  225.   This command will return the current working directory.
  226. Ñ removeMenu <name> - remove menu 'name' from menubar.
  227. Ñ removeTMark <name> - remove temporary mark.
  228. Ñ replaceText <pos1> <pos2> <text> - replaces the text
  229.   between 'pos1' and 'pos2' with 'text'.
  230. Ñ rm <fileName>
  231.   This command will delete the file fileName.
  232. Ñ rowColToPos <row> <col> - converts to abosolute position.
  233. Ñ search <pattern> <pos> [limit] [noFail] - searches for 
  234.   'pattern' from position 'pos' using current values of
  235.   'forward', 'matchWords', 'ignoreCase', and 'regExpr'. 
  236.   If 'limit' is specified, the search fails if the a 
  237.   match is not found totally contained between 'pos' and
  238.   'limit'. If any fourth argument is specified, a search
  239.   failure still results TCL_OK. However, the result of
  240.   the call is then just an empty string. If the search
  241.   succeeds, a list of two positions will be returned. 
  242.   The first is the starting position of the match, the
  243.   second is one past the last character.
  244. Ñ select <pos1> <pos2> - selects the text between 'pos1' 
  245.   and 'pos2'.
  246. Ñ selEnd - returns the end of the hilited selection, or 
  247.   the current insertion point if no text is selected.
  248. Ñ sendToBack <winName> - Sent named window to back.
  249. Ñ setfinfo <fileName> [-a flags] [-c fdCreator] [-t fdTypes]
  250.   This command will set the standard Macintosh file information. The flags setting 
  251.   must be of the same format as displayed by the getfinfo flag.
  252. Ñ setFSets - (see the File Sets section).
  253. Ñ setVar <name> <value> - Sets the Alpha variable 'name' 
  254.   to 'value'.
  255. Ñ sizeWin [win name] <width> <height> - sets size of current or specified window.
  256. Ñ substituteVars <string> - Takes a single string and
  257.   substitutes for all variables inside it, regardless of
  258.   depth. Unfortunately, you currently need to make 'global var' 
  259.   declarations in the proc you call this for each 'var' that might need 
  260.   to be substituted in the string (see proc.tcl for examples).
  261. Ñ switchTo <appName> - Switches to application 'appName'.
  262. Ñ tclResult - displays a dialog showing the result of 
  263.   the last TCL evaluation.
  264. Ñ ticks
  265.   Returns the current TickCount. Ticks are 60ths of a seconds. TickCount is the 
  266.   number of ticks since the Macintosh was started. The command:
  267.         puts stdout [expr "[ticks] / 60"]
  268.   will print the number of seconds since the Macintosh was booted.
  269. Ñ traceFunc on <funcName> <winName> Trace 'funcName', send output to 
  270.                                     'winName'. 
  271.   traceFunc off                        Turn function tracing off.
  272.   traceFunc status                    Display current tracing status.
  273. Ñ winNames - return a TCL list of all open windows.
  274. Ñ wrapText
  275. Ñ xtclcmd [-f filename] <cmdname> [argument_list]...
  276.   This command will load the external command cmdname and pass it the argument 
  277.   list [ cmdname argument_list... ]. External command are code resources of type 
  278.   XTCL. They may be located in the resource fork of the tickle application, or they 
  279.   may be located in a file named XTCL File in the same directory as the tickle 
  280.   application. If the optional -f filename is included, the external command will first 
  281.   be loaded from filename before the other two files.
  282.   See the appendix for a detailed description of the external tcl command interface. 
  283.   See the accompanying sources for an example of writing an XTCL.
  284.